… scan)

Ports qipc's `qipc/_src/core/block/scan.py` into Quadrants as
`qd.simt.block.inclusive_{add,min,max}` and
`qd.simt.block.exclusive_{add,min,max}`, plus the generic
`block.{inclusive,exclusive}_scan(..., op, [identity,] dtype)` for
custom monoids.  Closes the second of three block-tier rows in
`qipc_gaps_block.md`.

Strategy is CUB's `BLOCK_SCAN_WARP_SCANS`: per-warp Hillis-Steele scan
via `subgroup.{_inclusive_scan, _exclusive_scan}` -> last lane of
every warp publishes the warp aggregate to a
`SharedArray(NUM_WARPS, dtype)` -> `block.sync()` -> every thread
sequentially folds the cross-warp prefix and applies its own warp's
prefix to its scan value.  Cross-warp prefix is computed redundantly
on every thread to avoid a second barrier (same trade-off CUB makes).

Inclusive: warp aggregate at the last lane is just the inclusive
value, written directly.  Exclusive: warp aggregate is recovered as
`op(exclusive[last_lane], value[last_lane])`, since the exclusive
scan does not include the last lane's input.  When the block is
exactly one warp the cross-warp shared-mem path is short-circuited at
trace time.

API mirrors the new block reduce: caller passes `tid` explicitly,
`block_dim` and `log2_warp` are `template()`.  `exclusive_add`
derives the additive identity from `value - value` (matches
`subgroup.exclusive_add`); `exclusive_min` / `exclusive_max` take an
explicit `identity` because no portable type-extreme is derivable
from `value` alone (matches `subgroup.exclusive_min`).

Tests in `tests/python/test_simt.py` parametrise over
`{i32, f32} x {block_dim ∈ [32, 128, 256]}`, asserting per-thread
against a sequential CPU oracle.  Min / max use a permuted
(non-monotone) input so the scan result genuinely depends on every
prefix step, not just the trailing or leading element.  Run on
`arch=qd.gpu` so CUDA, AMDGPU, Vulkan, and Metal CI all exercise the
ports.

Documentation updated in `docs/source/user_guide/block.md`: support
table grows two rows; new `block.inclusive_*` and `block.exclusive_*`
sections explain the contract, identity rules, and the cost profile.

Ports qipc's `qipc/_src/core/sort/_block_radix_rank.py` into Quadrants
as `qd.simt.block.radix_rank_match_atomic_or`.  Closes the third (and
final) row in `qipc_gaps_block.md`.

Faithful port of CUB's
`BlockRadixRankMatchEarlyCounts<WARP_MATCH_ATOMIC_OR>` from
`cub/block/block_radix_rank.cuh` (the SM90 onesweep policy):

  1. Per-warp digit histograms via shared-memory atomic_add.
  2. Per-thread column-sum upsweep across warps (rewrites warp
     histograms into per-warp running prefixes; yields per-thread
     bin_count for digit == tid).
  3. Block exclusive scan on bin_count (uses our newly-added
     `block.exclusive_add`).
  4. Downsweep: fold the block-wide exclusive prefix into every warp's
     offset entry.
  5. Per-key match via shared-memory atomic_or on a per-digit lane
     mask; leader (highest set lane) does a single atomic_add on the
     warp offset and broadcasts via `subgroup.shuffle`; each thread's
     rank = warp_offset + popc(bin_mask & lanemask_le) - 1.
  6. Publish bins + exclusive_digit_prefix to caller-supplied
     SharedArray outparams; one block.sync() retires before exit so
     the caller can read them without an extra barrier.

Improvements over the qipc port:

  - WARP_SYNC (qipc's `warp.ballot(qd.cast(1, qd.i32))` hack) is
    replaced by `subgroup.sync()` which lowers to `__syncwarp` /
    `OpControlBarrier(ScopeSubgroup, ...)` / `s_barrier` on the
    appropriate backend.
  - CUB's `LaneMaskLe()` PTX intrinsic + qipc's `_lane_mask_le`
    workaround function are replaced by the new portable
    `subgroup.lanemask_le(invocation_id())` (saves ~13 LoC and
    sidesteps the lane==31 overflow special case).
  - `BlockScan::ExclusiveSum` is replaced by the just-added
    `block.exclusive_add`, which drops the qipc kernel's reliance on
    a private sequential cross-warp scan.

API: `radix_rank_match_atomic_or(key, tid, block_dim, log2_warp,
radix_bits, bit_start, num_bits, bins, excl_prefix)` — `key` is one
u32 per thread; `bins` and `excl_prefix` are
`block.SharedArray((1 << radix_bits,), qd.i32)` outparams.  Returns
the per-thread stable rank.  Currently constrained to
`block_dim == 1 << radix_bits`, `log2_warp == 5` (wave32), and
`items_per_thread == 1`; multi-item and wave64 paths are future work.

Tests in `tests/python/test_simt.py` exercise three input
distributions against a CPU oracle:
  - low_entropy: 16 distinct digits each repeated 16 times (heavy
    match-path traffic with several lanes per warp colliding).
  - uniform: full 16-bit uniform random.
  - uniform_high_bits: digit drawn from bits [8, 16) (covers
    bit_start > 0).

The oracle checks bins, excl_prefix, and the per-thread ranks
(uniqueness as a permutation of [0, 256) plus value match).  Run on
`arch=qd.gpu`.

Documentation updated in `docs/source/user_guide/block.md`: support
table grows one row, new section explains the constraints, args,
cost, and shows a worked example.

`subgroup.sync()` lowers to `OpControlBarrier(ScopeSubgroup, ScopeSubgroup, 0)`
on SPIR-V — i.e. the Memory Semantics operand is **0**.  Bare control
barriers without memory semantics do not publish prior shared-memory
writes to other lanes, so on Vulkan / Metal the radix-rank algorithm
silently saw stale `atomic_or` / `atomic_add` results across the warp,
producing off-by-one ranks (e.g. `actual_ranks[14] == 15` vs
`expected[14] == 14` on the uniform_high_bits pattern).

Wrap the WARP_SYNC pattern in `_warp_sync_fence()` which issues both
`subgroup.sync()` and `subgroup.mem_fence()`.  On CUDA, the explicit
mem_fence is a redundant `__threadfence_block` — slight overhead but
always correct.  On SPIR-V, the mem_fence emits a real
`OpMemoryBarrier(ScopeSubgroup, AcquireRelease | UniformMemory |
WorkgroupMemory)` and restores CUB's `__syncwarp` shared-memory
visibility invariant that the algorithm depends on.

Replaces three `subgroup_sync()` call-sites in
`radix_rank_match_atomic_or`: the histogram-zero retire, the post
`atomic_or` retire, and the leader-clear retire.

The longer-term fix is to emit the proper memory semantics on
`subgroupBarrier` in `spirv_codegen.cpp` (matching the pattern used
by `subgroupMemoryBarrier`), but that lives on the subgroup branch /
needs its own runtime rebuild — handle here in user code so this PR
stays self-contained.

The Vulkan / Metal radix-rank failures were not the SPIR-V
subgroupBarrier-without-memory-semantics quirk after all: pairing
sync() with mem_fence() was correct for general robustness but did not
fix the test.

Real bug: ``leader = 31 - clz(cast(bin_mask, i32))`` triggered SPIR-V's
GLSL.std.450 FindSMsb on the i32, which for negative values (top bit
set) returns the index of the most-significant **0**-bit, not the
1-bit.  Concretely, when only the highest lane in a warp has a given
digit, bin_mask = 0x80000000; FindSMsb on (i32)-2147483648 returns 30
(bit 30 is the highest 0-bit), so the leader was elected as lane
``31 - 30 = 1`` instead of lane 31.  All non-leader lanes in the
match group then read warp_offset from lane 1 (which had stale 0
because lane 1 was *not* the actual leader and never atomic_add'd),
producing the observed last-lane-of-warp off-by-one ranks.

Fix: pass the u32 directly to ``clz`` so SPIR-V dispatches FindUMsb
(which returns MSB-of-1 unconditionally and is already cross-backend on
the subgroup branch).  This matches what CUB's ``__clz`` does on CUDA
and what AMDGPU emits via the new amdgcn-clz lowering.

Restore the ``_warp_sync_fence`` (subgroup.sync + subgroup.mem_fence)
calls in the match phase — they're orthogonal to the clz fix but
remain the right thing for memory visibility across the warp on
SPIR-V (whose ``OpControlBarrier(ScopeSubgroup, ScopeSubgroup, 0)``
has no memory semantics; pairing it with an explicit
``OpMemoryBarrier(ScopeSubgroup, AcqRel | UniformMem | WorkgroupMem)``
restores CUDA ``__syncwarp``'s shared-memory visibility invariant).

CUDA was unaffected because ``__clz`` ignores signedness (counts
leading zeros bit-pattern-wise) — the failure only showed up on the
SPIR-V GLSL extended instruction set.

…p/new-qipc-ops-block

…ally

Every block-scope reduction, scan, and the radix-rank primitive previously
took log2_warp as a template parameter, requiring callers to plumb in 5 on
wave32 backends or 6 on wave64.  Now that subgroup.group_size() and
subgroup.log2_group_size() return compile-time Python ints (32 on CUDA /
Metal / Vulkan-on-NVIDIA, 64 on AMDGPU), each block op reads the subgroup
size itself and the parameter is no longer plumbed at the call site.

Adds a compile-time guard (impl.static_assert) at the top of every block op
that block_dim is a positive multiple of subgroup.group_size() -- catches
misconfigurations like block_dim=32 on AMDGPU (wave64) with a clear error
message instead of a silent NUM_WARPS=0 miscompile.

The radix-rank op also gains a compile-time assert that subgroup.group_size()
is 32: the atomic-OR match path is built on 32-lane i32 ballot masks, and
the wave64 path is not yet implemented (parallel to the existing constraint
in the docstring).

The base branch already did this sweep across most user-facing docs and
docstrings; these mentions slipped in after the original cleanup and from
test_atomic.py which the sweep missed.  No semantic change.

…es Python ints

Inside a @qd.func body, plain Python ops like block_dim % WARP_SIZE get
traced into Quadrants Expressions rather than evaluated as Python ints, so
the new compile-time guards in reduce / scan / radix_rank were failing with
"Static assert with non-static condition" on every backend.

Restoring the impl.static(...) wrappers around the template-int arithmetic
(WARP_SIZE, NUM_WARPS, BLOCK_WARPS, the static_assert condition, SharedArray
shape tuples, and the per-iteration shared-memory indices) forces evaluation
at trace time and the constants reach static_assert / SharedArray as plain
Python ints again, matching the pre-API-cleanup shape.

Pure correctness fix; semantically equivalent to the previous shape.

block.py is cross-GPU code -- its abstractions (block, subgroup, lane,
shuffle, ballot) come from the SPIR-V / Vulkan / portable subgroup model,
not from CUDA's warp model.  Calling the per-subgroup step a "warp" leaks
CUDA terminology into a portable surface.  This commit sweeps every
cross-GPU identifier and prose mention from "warp" to "subgroup", and
leaves only the genuinely CUDA-specific terms intact (``__syncwarp`` in
comments documenting CUDA's primitive, and the legacy ``qd.simt.warp.*``
test module which is CUDA-only).

block.py identifier renames:
  WARP_SIZE        -> SUBGROUP_SIZE
  WARP_THREADS     -> SUBGROUP_THREADS    (radix-rank local)
  log2_warp        -> log2_subgroup
  NUM_WARPS        -> NUM_SUBGROUPS
  BLOCK_WARPS      -> BLOCK_SUBGROUPS
  warp_id          -> subgroup_id
  warp_idx         -> subgroup_idx
  warp_agg         -> subgroup_agg
  warp_prefix      -> subgroup_prefix
  warp_count       -> subgroup_count
  warp_offset      -> subgroup_offset
  j_warp           -> j_subgroup           (radix-rank loop var)
  _warp_sync_fence -> _subgroup_sync_fence
  CUB stage names: ComputeHistogramsWarp / ComputeOffsetsWarpUpsweep /
  ComputeOffsetsWarpDownsweep -> ...Subgroup / ...SubgroupUpsweep /
  ...SubgroupDownsweep (algorithm-internal names, not exported anywhere).

block.md:
  Deletes the stale ``**`` footnote paragraph that claimed AMDGPU callers
  must pass log2_warp=6 -- the parameter no longer exists; subgroup size
  is read from subgroup.group_size() at compile time, and the same source
  compiles correctly on wave32 and wave64.  Sweeps prose "warp" ->
  "subgroup" in the algorithm descriptions and cost expressions.  Keeps
  "subgroup (warp / wavefront)" in the dual-term glossary line.

test_simt.py:
  Sweeps prose in our block-reduce / block-scan / block-radix-rank
  section headers.  Rewrites the stale ``log2_warp is pinned to 5``
  comment to reflect the current compile-time auto-detection.  Leaves
  the legacy qd.simt.warp.* tests, the segmented-reduce tests, and the
  ``__syncwarp`` mention in test_block_sync untouched.

Pure rename + doc cleanup; identical IR.

Block reduce / scan / radix-rank impls require ``block_dim`` to be a positive multiple
of the subgroup size (enforced by ``impl.static_assert``).  AMDGPU is wave64 in
Quadrants, so the existing ``block_dim=32`` parametrization is degenerate there: it
fails at compile time with ``block.reduce: block_dim must be a positive multiple of
subgroup size``.

Add ``_skip_if_block_dim_lt_subgroup`` and call it from all 12 block-* dim-parametrized
tests.  CUDA / Vulkan / Metal still cover the full ``[32, 128, 256]`` matrix; AMDGPU
exercises ``[128, 256]``.  Also refresh the section-header comment to reflect the wave64
regime.

Picks up '[subgroup] test: lean parameterization for sized reduce / scan tests'.

Three assertion-message wrappings updated by black 25.1.0 (the version pinned in
.pre-commit-config.yaml).  Pure formatting; no semantic changes.

…ve64

block.md still said radix_rank requires subgroup_size == 32 and that AMDGPU
(wave64) is unsupported; that's been fixed.  Update the constraints bullet to
reflect the wave32 / wave64 dispatch and refresh the shared-memory footprint
breakdown to call out the wave-size-specific match-mask region (4 KiB i32 on
wave32, 8 KiB i64 on wave64).